/*-
 * #%L
 * HAPI FHIR JPA Server - International Patient Summary (IPS)
 * %%
 * Copyright (C) 2014 - 2025 Smile CDR, Inc.
 * %%
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * #L%
 */
package ca.uhn.fhir.jpa.ips.api;

import ca.uhn.fhir.jpa.ips.strategy.BaseIpsGenerationStrategy;
import ca.uhn.fhir.rest.api.server.RequestDetails;
import ca.uhn.fhir.rest.param.TokenParam;
import ca.uhn.fhir.rest.server.exceptions.ResourceNotFoundException;
import jakarta.annotation.Nonnull;
import jakarta.annotation.Nullable;
import org.hl7.fhir.instance.model.api.IBaseBundle;
import org.hl7.fhir.instance.model.api.IBaseResource;
import org.hl7.fhir.instance.model.api.IIdType;

import java.util.List;

/**
 * This interface is the primary configuration and strategy provider for the
 * HAPI FHIR International Patient Summary (IPS) generator.
 * <p>
 * Note that this API will almost certainly change as more real-world experience is
 * gained with the IPS generator.
 */
public interface IIpsGenerationStrategy {

	/**
	 * This method returns the profile associated with the IPS document
	 * generated by this strategy. This URL will be added to generated
	 * IPS Bundles in <code>Bundle.meta.profile</code>, and can also
	 * be used to support the <code>profile</code> parameter on the
	 * <code>$summary</code> operation.
	 */
	String getBundleProfile();

	/**
	 * This method will be called once by the framework. It can be
	 * used to perform any initialization.
	 */
	void initialize();

	/**
	 * This method should return a list of the sections to include in the
	 * generated IPS. Note that each section must have a unique value for the
	 * {@link Section#getProfile()} value.
	 */
	@Nonnull
	List<Section> getSections();

	/**
	 * Returns the resource supplier for the given section. The resource supplier
	 * is used to supply the resources which will be used for a given
	 * section.
	 *
	 * @param theSection The section
	 */
	@Nonnull
	ISectionResourceSupplier getSectionResourceSupplier(@Nonnull Section theSection);

	/**
	 * Provides a list of configuration property files for the IPS narrative generator.
	 * <p>
	 * Entries should be of the format <code>classpath:path/to/file.properties</code>
	 * </p>
	 * <p>
	 * If more than one file is provided, the files will be evaluated in order. Therefore you
	 * might choose to include a custom file, followed by
	 * {@link BaseIpsGenerationStrategy#DEFAULT_IPS_NARRATIVES_PROPERTIES}
	 * in order to fall back to the default templates for any sections you have not
	 * provided an explicit template for.
	 * </p>
	 */
	List<String> getNarrativePropertyFiles();

	/**
	 * Create and return a new <code>Organization</code> resource representing.
	 * the author of the IPS document. This method will be called once per IPS
	 * in order to
	 */
	IBaseResource createAuthor();

	/**
	 * Create and return a title for the composition document.
	 *
	 * @param theContext The associated context for the specific IPS document being generated.
	 */
	String createTitle(IpsContext theContext);

	/**
	 * Create and return a confidentiality code for the composition document. Must be a valid
	 * code for the element <code>Composition.confidentiality</code>
	 *
	 * @param theIpsContext The associated context for the specific IPS document being generated.
	 */
	String createConfidentiality(IpsContext theIpsContext);

	/**
	 * This method is used to determine the resource ID to assign to a resource that
	 * will be added to the IPS document Bundle. Implementations will probably either
	 * return <code>null</code> to leave the resource ID as-is, or generate a
	 * placeholder UUID to replace it with.
	 * <p>
	 * If you want to replace the native resource ID with a placeholder so as not
	 * to leak the server-generated IDs, the recommended way is to
	 * return <code>IdType.newRandomUuid()</code>
	 * </p>
	 *
	 * @param theIpsContext The associated context for the specific IPS document being
	 *                      generated. Note that this will be <code>null</code> when
	 *                      massaging the ID of the subject (Patient) resource, but will
	 *                      be populated for all subsequent calls for a given IPS
	 *                      document generation.
	 * @param theResource   The resource to massage the resource ID for
	 * @return An ID to assign to the resource, or <code>null</code> to leave the existing ID intact,
	 * meaning that the server-assigned IDs will be used in the bundle.
	 */
	@Nullable
	IIdType massageResourceId(@Nullable IpsContext theIpsContext, @Nonnull IBaseResource theResource);

	/**
	 * Fetches and returns the patient to include in the generated IPS for the given patient ID.
	 *
	 * @throws ResourceNotFoundException If the ID is not known.
	 */
	@Nonnull
	IBaseResource fetchPatient(IIdType thePatientId, RequestDetails theRequestDetails) throws ResourceNotFoundException;

	/**
	 * Fetches and returns the patient to include in the generated IPS for the given patient identifier.
	 *
	 * @throws ResourceNotFoundException If the ID is not known.
	 */
	@Nonnull
	IBaseResource fetchPatient(TokenParam thePatientIdentifier, RequestDetails theRequestDetails);

	/**
	 * This method is called once for each generated IPS document, after all other processing is complete. It can
	 * be used by the strategy to make direct manipulations prior to returning the document.
	 */
	default void postManipulateIpsBundle(IBaseBundle theBundle) {
		// nothing
	}
}
